Skip to main content

Synchronizer Operations

See the cheatsheet for every operations here: Overview.

After initializing Synchronizer from above steps, these methods are supported.

GET an item​

GET a single item given an id or path of item

Parameters

A JS object with following fields

  • path string: path to file
  • id string: id of file

    either path or id is required, not both.

  • unserializeItem boolean optional: whether to return JS object (true) or string (false), default=false.

Response​

  • Return string (unserialize = false) or Item (unserialize = true). Return null if errors.

Example​

const data: string = getItem({ path: "My first note.md" });

GET multiple items​

GET multiple items from remote using their IDs

Parameters

A JS object with following fields

  • ids string[]: array of item IDs to retrieve
  • unserializeAll boolean optional: whether to return JS objects (true) or strings (false), default=false

Response​

  • Return array of Items (unserializeAll = true) or array of strings (unserializeAll = false). Similar to getItem, paths are not supported.

Example​

const items: Item[] = getItems({ ids: ["id1", "id2"], unserializeAll: true });

GET items metadata​

GET items metadata from remote with optional timestamp filtering

Parameters

A JS object with following fields

  • context object: context object containing optional timestamp
    • timestamp number optional: timestamp in unixMs, retrieve items with .updated_time field after timestamp (inclusive), useful for delta or detecting new items
  • outputLimit number optional: maximum number of items to retrieve, default=50

Response​

  • Return object containing:
    • items: array of Item objects
    • hasMore: boolean indicating if there are more items to fetch
    • context: object with timestamp for next fetch

Example​

const result = getItemsMetadata({
  context: { timestamp: 1640995200000 },
  outputLimit: 100,
});

UPDATE an item​

UPDATE an item with conflict detection using timestamp matching

Parameters

A JS object with following fields

  • item Item: the item object to update
  • lastSync number: timestamp in unixMs, must match the item's .updated_time field on remote to avoid conflicts

Response​

  • Return object containing:
    • status: "conflicted" | "inaccurate timestamp" | "succeeded"
    • message: descriptive message
    • remoteItem: (when conflicted) the current remote item for conflict resolution
    • newItem: (when succeeded) the updated item
    • oldItem: (when succeeded) the previous item version
    • newSyncTime: (when succeeded) updated timestamp for next sync

Example​

const result = updateItem({
  item: myItem,
  lastSync: 1640995200000,
});

CREATE multiple items​

CREATE multiple items on remote with automatic ID generation

Parameters

A JS object with following fields

  • items Item[]: array of items to create, should at least have .type* field. For resources (type* == 4), provide a path to the resource

Response​

  • Return object containing:
    • createdItems: array of successfully created items
    • failedItems: array of objects with item and error information

Example​

const result = createItems({
  items: [
    { type_: 1, title: "New Note", body: "Note content" },
    { type_: 4, filename: "image.png" },
  ],
});

DELETE multiple items​

DELETE multiple items from remote, including resources and their metadata

Parameters

A JS object with following fields

  • deleteItems Item[]: array of items to delete, should have .type* field and id. For resources (type* == 4), both blob and metadata will be deleted

Response​

  • Return object containing:
    • status: "succeeded" | "item not found" | "could not delete item" | "read-only item can't be deleted"
    • item: the processed item (optional)
    • error: error information if deletion failed (optional)

Example​

const result = deleteItems({
  deleteItems: [
    { id: "item1", type_: 1 },
    { id: "resource1", type_: 4 },
  ],
});

VERIFY sync info​

VERIFY sync info version and E2E settings on remote. This is run automatically before every operations above, you don't need to run this manually if not needed.

Parameters

A JS object with following fields

  • E2E object: E2E configuration object
    • ppk PublicPrivateKeyPair optional: public-private key pair
    • e2ee boolean: whether end-to-end encryption is enabled

Response​

  • Return object containing:
    • status: "success" | "aborted"
    • message: descriptive message
    • remoteSyncInfo: remote sync info object for debugging (optional)

Example​

const result = verifySyncInfo({
  E2E: {
    e2ee: true,
    ppk: keyPair,
  },
});